Improve Timeout.timeout documentation formatting and typos #92
Conversation
This commit makes a few minor improvements to the documentation of the `Timeout.timeout` method. The changes include fixing typos and enhancing formatting for better readability. We can see the latest version of the documentation here: https://docs.ruby-lang.org/en/master/Timeout.html#method-c-timeout Also, we can verify this change locally by running: ```shell rdoc open doc/Timeout.html ```
| # is that Timeout::Error inherits from RuntimeError and might be caught unexpectedly by +rescue+. | ||
| # Timeout::ExitException inherits from Exception so it will only be rescued by <tt>rescue Exception</tt>. |
There was a problem hiding this comment.
As I understand those cases will be fixed by @st0012's work to better support Markdown in RDoc, is that correct?
If so I'm not so inclined to have HTML tags here, it looks pretty messy.
There was a problem hiding this comment.
It will fix the rendering though, and the other changes look good so I guess let's go with that for now, and then maybe go back to backticks once RDoc supports them.
There was a problem hiding this comment.
Yeah if we update RDoc to 7.10 then we can use backticks in rdoc markup too.
There was a problem hiding this comment.
Do you know when that would happen for ruby/ruby? (since it doesn't seem to work for https://docs.ruby-lang.org/en/master/Timeout.html#method-c-timeout)
There was a problem hiding this comment.
It's interesting because the rescue one line above is now correctly rendered. And this line is rendered as ‘rescue Exception`. I wonder if the beginning quote is actually not a backtick character 🤔
There was a problem hiding this comment.
In RDoc format, Only `single_word` is allowed mainly because of the restriction using regexp and gsub in parsing (I think).
Remaining backticks and quotes are converted to multibyte quotes ‘’”“
There was a problem hiding this comment.
Ah that's unfortunate, is there already an issue about that? (I didn't find one, only related ruby/rdoc#1230)
What's the correct workaround for now for multi-word code quoting? <tt>some code</tt>?
There was a problem hiding this comment.
<tt> (or use ` with markup: markdown) is the only way for now.
I think there is no issue yet.
There was a problem hiding this comment.
Thanks for confirming, I filed ruby/rdoc#1565.
And then I will merge this for now as there is no better way.
|
@ybiquitous Thank you for these fixes! |
|
Thanks, too. I look forward to seeing the backtick support in the next RDoc release. 😄 |
4 participants
This PR makes a few minor improvements to the documentation of the
Timeout.timeoutmethod. The changes include fixing typos and enhancing formatting for better readability.We can see the latest version of the documentation here:
https://docs.ruby-lang.org/en/master/Timeout.html#method-c-timeout
Also, we can verify this change locally by running: